<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
 <head>
  <meta http-equiv="content-type" content="text/html; charset=UTF-8">
  <title>Filter</title>

 </head>
 <body><div class="manualnavbar" style="text-align: center;">
 <div class="prev" style="text-align: left; float: left;"><a href="mysqlnd-ms.rwsplit.html">Read-write splitting</a></div>
 <div class="next" style="text-align: right; float: right;"><a href="mysqlnd-ms.qos-consistency.html">Service level and consistency</a></div>
 <div class="up"><a href="mysqlnd-ms.concepts.html">Concepts</a></div>
 <div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="mysqlnd-ms.filter" class="section">
  <h2 class="title">Filter</h2>
  <blockquote class="note"><p><strong class="note">Note</strong>: 
   <strong>Version requirement</strong><br />
   <p class="para">
    Filters exist as of mysqlnd_ms version 1.1.0-beta.
   </p>
  </p></blockquote>
  <p class="para">
   <a href="mysqlnd-ms.plugin-ini-json.html" class="link">filters</a>.
   PHP applications that implement a MySQL replication cluster must first identify
   a group of servers in the cluster which could execute a statement before
   the statement is executed by one of the candidates. In other words: a defined
   list of servers must be filtered until only one server is available.
  </p>
  <p class="para">
   The process of filtering may include using one or more filters, and filters can be
   chained. And they are executed in the order they are defined in the plugins
   configuration file.
  </p>
  <blockquote class="note"><p><strong class="note">Note</strong>: 
   <strong>Explanation: comparing filter chaining to pipes</strong><br />
   <p class="para">
    The concept of chained filters can be compared to using pipes to connect
    command line utilities on an operating system command shell. For example,
    an input stream is passed to a processor, filtered, and then transferred
    to be output. Then, the output is passed as input to the next command,
    which is connected to the previous using the pipe operator.
   </p>
  </p></blockquote>
  <p class="para">
   Available filters:
   <ul class="itemizedlist">
    <li class="listitem">
     <span class="simpara">
      Load balancing filters:
      <a href="mysqlnd-ms.plugin-ini-json.html#ini.mysqlnd-ms-plugin-config-v2.filters" class="link">random</a> and
      <a href="mysqlnd-ms.plugin-ini-json.html#ini.mysqlnd-ms-plugin-config-v2.filters" class="link">roundrobin</a>.
     </span>
    </li>
    <li class="listitem">
     <span class="simpara">
      Selection filter:
      <a href="mysqlnd-ms.plugin-ini-json.html#ini.mysqlnd-ms-plugin-config-v2.filters" class="link">user</a>,
      <a href="mysqlnd-ms.plugin-ini-json.html#ini.mysqlnd-ms-plugin-config-v2.filters" class="link">user_multi</a>,
      <a href="mysqlnd-ms.plugin-ini-json.html#ini.mysqlnd-ms-plugin-config-v2.filters" class="link">quality_of_service</a>.
     </span>
    </li>
   </ul>
  </p>

  <p class="para">
   The <em>random</em> filter implements the &#039;random&#039; and &#039;random once&#039;
   load balancing policies. The &#039;round robin&#039; load balancing can be configured
   through the <em>roundrobin</em> filter. Setting a &#039;user defined
   callback&#039; for server selection is possible with the <em>user</em>
   filter. The <em>quality_of_service</em> filter finds cluster
   nodes capable of delivering a certain service, for example, read-your-writes or,
   not lagging more seconds behind the master than allowed.
  </p>
  <p class="para">
   Filters can accept parameters to change their behaviour.
   The <em>random</em> filter accepts an optional
   <em>sticky</em> parameter. If set to true, the filter changes
   load balancing from random to random once. Random picks a random server
   every time a statement is to be executed. Random once picks a random
   server when the first statement is to be executed and uses the same
   server for the rest of the PHP request.
  </p>
  <p class="para">
   One of the biggest strength of the filter concept is the possibility to
   chain filters. This strength does not become immediately visible because
   tje <em>random</em>, <em>roundrobin</em> and
   <em>user</em> filters  are supposed to output no more than one server.
   If a filter reduces the list of candidates for running a statement to
   only one server, it  makes little sense to use that one server as
   input for another filter for  further reduction of the list of candidates.
  </p>
  <p class="para">
   An example filter sequence that will fail:
   <ul class="itemizedlist">
    <li class="listitem">
     <span class="simpara">
      Statement to be executed: <em>SELECT 1 FROM DUAL</em>. Passed to all filters.
     </span>
    </li>
    <li class="listitem">
     <span class="simpara">
      All configured nodes are passed as input to the first filter.
      Master nodes: <em>master_0</em>.
      Slave nodes:<em>slave_0</em>, <em>slave_1</em>
     </span>
    </li>
    <li class="listitem">
     <span class="simpara">
      Filter: <em>random</em>, argument <em>sticky=1</em>.
      Picks a random slave once to be used for the rest of the PHP request.
      Output: <em>slave_0</em>.
     </span>
    </li>
    <li class="listitem">
     <span class="simpara">
      Output of <em>slave_0</em> and the statement to be executed
      is passed as input to the next filter. Here: <em>roundrobin</em>,
      server list passed to filter is: <em>slave_0</em>.
     </span>
    </li>
    <li class="listitem">
     <span class="simpara">
      Filter: <em>roundrobin</em>. Server list consists of
      one server only, round robin will always return the same server.
     </span>
    </li>
   </ul>
   If trying to use such a filter sequence,
   the plugin may emit a warning like <em>(mysqlnd_ms) Error while creating
   filter &#039;%s&#039; . Non-multi filter &#039;%s&#039; already created. Stopping in %s on
   line %d</em>. Furthermore, an appropriate error on the connection handle
   may be set.
  </p>
  <p class="para">
   A second type of filter exists: multi filter. A multi filter emits zero, one or multiple
   servers after processing. The <em>quality_of_service</em> filter
   is an example. If the service quality requested sets an upper limit for the slave
   lag and more than one slave is lagging behind less than the allowed number of seconds,
   the filter returns more than one cluster node. A multi filter must be followed by other
   to further reduce the list of candidates for statement execution until a candidate
   is found.
  </p>
  <p class="para">
   A filter sequence with the <em>quality_of_service</em>
   multi filter followed by a load balancing filter.
   <ul class="itemizedlist">
    <li class="listitem">
     <span class="simpara">
      Statement to be executed: <em>SELECT sum(price) FROM orders WHERE order_id = 1</em>.
      Passed to all filters.
     </span>
    </li>
    <li class="listitem">
     <span class="simpara">
      All configured nodes are passed as input to the first filter.
      Master nodes: <em>master_0</em>.
      Slave nodes: <em>slave_0</em>, <em>slave_1</em>,
      <em>slave_2</em>, <em>slave_3</em>
     </span>
    </li>
    <li class="listitem">
     <span class="simpara">
      Filter: <em>quality_of_service</em>, rule set: session_consistency (read-your-writes)
      Output: <em>master_0</em>
     </span>
    </li>
    <li class="listitem">
     <span class="simpara">
      Output of <em>master_0</em>
      and the statement to be executed
      is passed as input to the next filter, which is <em>roundrobin</em>.
     </span>
    </li>
    <li class="listitem">
     <span class="simpara">
      Filter: <em>roundrobin</em>. Server list consists of
      one server. Round robin selects <em>master_0</em>.
     </span>
    </li>
   </ul>
  </p>
  <p class="para">
   A filter sequence must not end with a multi filter. If trying to use
   a filter sequence which ends with a multi filter the plugin may emit a
   warning like <em>(mysqlnd_ms) Error in configuration. Last filter is multi
   filter. Needs to be non-multi one. Stopping in %s on line %d</em>.
   Furthermore, an appropriate error on the connection handle
   may be set.
  </p>
  <p class="para">
   <blockquote class="note"><p><strong class="note">Note</strong>: 
   <strong>Speculation towards the future: MySQL replication filtering</strong><br />
   <p class="para">
    In future versions, there may be additional multi filters.
    For example, there may be a <em>table</em>
    filter to support MySQL replication filtering. This would allow
    you to define rules for which database or table is to be replicated to which
    node of a replication cluster. Assume your replication cluster
    consists of four slaves (<em>slave_0</em>, <em>slave_1</em>,
    <em>slave_2</em>, <em>slave_3</em>) two of which replicate a database named
    <em>sales</em> (<em>slave_0</em>, <em>slave_1</em>).
    If the application queries the database <em>slaves</em>, the
    hypothetical <em>table</em> filter reduces the list of possible
    servers to <em>slave_0</em> and <em>slave_1</em>. Because
    the output and list of candidates consists of more than one server, it is
    necessary and possible to add additional filters to the candidate list, for example, using
    a load balancing filter to identify a server for statement execution.
   </p>
  </p></blockquote>
  </p>
 </div><hr /><div class="manualnavbar" style="text-align: center;">
 <div class="prev" style="text-align: left; float: left;"><a href="mysqlnd-ms.rwsplit.html">Read-write splitting</a></div>
 <div class="next" style="text-align: right; float: right;"><a href="mysqlnd-ms.qos-consistency.html">Service level and consistency</a></div>
 <div class="up"><a href="mysqlnd-ms.concepts.html">Concepts</a></div>
 <div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
